Context-Sensitive Help
Context-sensitive help provides immediate assistance and information to users without requiring users to leave the context in which they are working. It helps answer questions like "What is this?" and "Why would I use this?", and provides information for a particular object and its context.
For example, in many applications, user interface controls such as windows and tabs have a help button. When users click on the help button, the application links users to a help topic specific to the context of the window. Some applications also embedded context-sensitive help topics into the window itself as an HTML pane. The application relies on an identifier such as a topic ID or file name to identify the specific help topic to display.
There are several methods for creating context-sensitive help links. In addition, different use different mechanisms to support context-sensitive help links. For example, some , such as Microsoft HTML Help, create a map file using topic aliases. Applications then use the topic IDs in the map file to provide links to context-sensitive help topics from within the application. Other do not have a mapping mechanism. However, these may support creating links to context-sensitive help topics using file names.
Map Files
Many application support the use of map files to deliver context-sensitive help. The topic IDs and map numbers are listed in a map file, which is a text file that typically has a .h extension. Applications can use the information in the map file to link users to the appropriate context-sensitive help topic.
Note: Some developers may use the term header file instead of map file.
There are some variations in the way context-sensitivity works depending on which supported ePublisher output format you use. For example, Microsoft HTML Help, Sun JavaHelp, and Oracle Help use map files.
Note: WebWorks Help, WebWorks Reverb, Dynamic HTML Help, and XML+XSL do not use map files.
When an application calls a context-sensitive help topic, it relies on the topic IDs and map numbers to identify the specific topic to display. Therefore, the topic IDs and map numbers must be embedded both in the application code and in the help system. If the topic IDs and map numbers do not match, the wrong topic (or no topic) displays when the user requests Help.
Following is a typical example of a Microsoft HTML Help map file: 
#define IDH_WDWTYPE     1001  
#define IDH_WDWENTER    1002  
#define IDH_WDWCANCEL   1003
In this example, IDH_WDWTYPE is a topic ID, and 1001 is the corresponding map number. These topic IDs and map numbers must be embedded in the software application and in your source documents.
Following is a typical example of a Sun JavaHelp and Oracle Help map file:
<mapID target="ch1_htm_999374" url="ch1.htm#999374">  
<mapID target="ch2_htm_999640" url="ch2.htm#999640">  
<mapID target="ch9_htm_999786" url="ch9.htm#999786">
In this example, ch1_htm_99374 is a topic ID, and ch1.htm#99374 is the target URL for the topic ID. These topic IDs must be embedded in the software application and in your source documents.
Planning for Context-Sensitive Help
Creating context-sensitive help requires you to collaborate with application developers. Because topic IDs and map numbers must be embedded in both the software application and in your source documents, you and the application developers must agree in advance on the values to use.
Before you create context-sensitive help topics, complete the following steps:
  1. Confirm with your application developers that the application supports context-sensitive help.
  2. Meet with your application developers to identify each context-sensitive help topic you need to create.
  3. Determine if you will use topic IDs or file names to create links to context-sensitive help topics.
  4. Discuss the process for referencing context-sensitive help topics from the application with your application developers. Writers and application developers have the following options for creating context-sensitive help links:
    • The writer chooses the topic IDs or file names and embeds them in the source documents. If the generated output supports map files, the writer performs the following steps:
      • The writer uses topic IDs inserted into source documents and ePublisher to generate a map file, also known as a header file, that contains the topic IDs defined by the writer and automatically generated mapping IDs.
      • The writer supplies the generated map file to the application developers to implement.
      Note: The writer must supply the header file along with the help system to the developers each time the writer updates the help system. This ensures correctly identified context-sensitive help topics each time.
    • Application developers choose the topic IDs or file names and then give the topic IDs or filenames to the writer to embed in the source documents. If the generated output supports map files, the application developers perform the following steps:
      • Application developers create the map file, or header file.
      • Application developers give the writer a copy of the map file, or header file, and the writer embeds the topic IDs from the map file into the source documents.
Note: The group context must be unique so that if there are the same topic ID's in a help system, the context sensitive pointer will go to the correct place in the help.
Topic ID and File Name Requirements
If you are creating context-sensitive help topics using topic IDs, topic IDs must follow these guidelines:
  • Must be unique
  • Must begin with an alphabetical character
  • May contain alphanumeric characters
  • May not contain special characters or spaces, with the exception of underscores ( _ )
Dynamic HTML, Eclipse Help, Microsoft HTML Help, Oracle Help, Sun, WebWorks Help, and WebWorks Reverb support the use of topic IDs to create context-sensitive help.
If you are creating context-sensitive help topics using file names, file names must follow these guidelines:
  • Must be unique
  • Must begin with an alphabetical character
  • May contain alphanumeric characters
  • May not contain special characters or spaces
XML+XSL support the use of file names to create context-sensitive help.
Was this helpful?
Last modified date: 01/28/2026